
/*
 * Copyright (C) 2008-2009 Archie L. Cobbs. All rights reserved.
 *
 * $Id: ObsoleteUpdate.java 261 2010-01-06 15:51:13Z archie.cobbs $
 */

package org.dellroad.sidekar.schema;

import org.dellroad.sidekar.Database;
import org.dellroad.sidekar.util.SidekarException;

/**
 * A {@link DatabaseUpdate} that should never actually be applied.
 *
 * <p>
 * Instances of this class can replace obsolete updates that should never be applied
 * to a database, e.g. when it is known that all existing instances of the database
 * have already been updated. This class provides a "replacement stub" that allows
 * obsolete update classes to be removed once they are no longer needed.
 *
 * <p>
 * Note that when creating a new database instance, the given updates are not actually
 * applied because the given schema model is assumed to be up-to-date.
 */
public class ObsoleteUpdate extends AbstractDatabaseUpdate {

    public static final String DEFAULT_MESSAGE = "obsolete update cannot be applied";

    private final String message;

    /**
     * Convenience constructor. Equivalent to:
     *
     *  <blockquote>
     *  {@code ObsoleteUpdate(name, null)}
     *  </blockquote>
     *
     * @param name unique name for this update
     * @throws IllegalArgumentException if {@code name} is invalid
     */
    public ObsoleteUpdate(String name) {
        this(name, null);
    }

    /**
     * Primary constructor.
     *
     * @param name unique name for this update
     * @param message exception message, or null to use {@link #DEFAULT_MESSAGE}
     * @throws IllegalArgumentException if {@code name} is invalid
     */
    public ObsoleteUpdate(String name, String message) {
        super(name);
        this.message = message != null ? message : DEFAULT_MESSAGE;
    }

    /**
     * This implementation always throws a {@link SidekarException}.
     *
     * @throws SidekarException always
     */
    public final void updateDatabase(Database db) {
        throw new SidekarException(message);
    }
}

